home *** CD-ROM | disk | FTP | other *** search
SLIPdial - a dialler for Archimedes !TCPIP version 0.34 ------------------------------------------ Slipdial is a script-driven dialler and general-control program for communications using !TCPIP. Its primary use is to initiate a connection with the network services provider (including dialling and logging-in) before handing over control to !TCPIP, and then to close down the connection cleanly when !TCPIP has finished. As well as the normal dialling and expect/send string functions for controlling your modem and negotiating a login, it also has many facilities to start and kill sub-tasks (both wimp-based and taskwindow-based); capturing and displaying messages from the remote computer; file handling; dialogue with the user; timer functions and more... For example, you can define new icons to be added to the icon bar, which can have script-defined menus associated with them, as well as predefined actions for when the user clicks on them or drops a file on them. Windows and controls -------------------- When slipdial starts, its icon appears on the icon bar. Clicking with SELECT on this icon opens the Status window, which tells you slipdial's state, and may allow selection of actions from a user-defined menu. Four icons down the right side of the window give access to a menu, perform a redial (if dialling), pause/unpause the script, or stop the script. If no script is loaded, either as a default or by the startup switches you used (see later), you can load and start one by dropping its file on the iconbar icon or on the status window, or you can select one from the status window menu. Most of the time, however, a script will be run automatically. Clicking on the slipdial icon with the ADJUST button opens the Control window. This window displays the script as it executes, incoming text from the serial port, and other status information. At the bottom of this window is an input field, which allows you to directly enter slipdial commands. Two menus are available from the Control window. Pressing MENU gives you the choice of listing various items - the script itself; the currently-defined menus; variables, tasks and alarms. Pressing MENU while holding down the CTRL key lets you change the current "Debug level". This controls how much information about script execution is displayed in the Control window (see the entry on the "debug" command for more information on the exact effects). The other window available from the slipdial icon - actually from its associated menu - is the "Choices" window. With this you can specify which windows to open, how large to make them, and whether to run a specified script automatically (you can drag a file to the writable field to set this). These choices can be saved as default actions for every time you run slipdial. The Status Window ----------------- If you have trouble getting slipdial to communicate with your modem, the status window contains some diagnotic aids in the form of 3 "LED's", in the lower right-hand corner of the window. These show the state of some of the more important serial control lines - from left to right: DTR (data terminal ready); CTS and CD (carrier detect). Of these, probably only DTR and CD are of very much interest - DTR indicates that the serial line is active and the modem is in a condition to be talked-to; while CD indicates that the modem is online and has established communication with the remote modem. Startup flags ------------- To override the auto-run option, hold down the ALT key while starting SLIPdial. Command-line startup flags include: -file <filename> runs a specified script file on startup. Example: run Slipdial:!Run -file SLIPdial:call_demon -quiet pevents status and control windows from being opened at startup. -auto autoruns the script Slipdial:default -sprite <size> specifies size of slipdial's internal sprite area, for addition of user icons. All startup flags/switches can be abbreviated to 1 significant character. For example: run slipdial:!Run -s 8000 -f Slipdial:call_demon Script language --------------- There's no consistancy to what's in the language; just whatever I thought might be useful. The language has evolved to be something like VMS DCL, in that commands are often modified by qualifiers (command/qualifier=value). It's even similar to DCL in its extreme lethargy of execution! One useful point to know is that the first line of a script MUST be: #slipdial and another is that that scriptfiles must have the "Text" filetype. The "#slipdial" comment at the start of the file prevents slipdial from attempting to load non-script textfiles. Events ------ Certain commands set up actions with may occur asynchronously, meaning they don't follow the normal flow of the script. These could include timed alarms, user menu selections, line-condition alarms, etc. For the sake of giving these a name, I shall call these "events". Though they can be a little hard to understand at first (they can make it hard to understand the "flow" of your script), many of the most useful script capabilities center around them. SLIPdial script syntax ---------------------- Many slipdial commands can take qualifiers, which alter their behaviour in some way. Command qualifiers are introduced with a slash (/) and may in some cases be followed by a value after an equals sign. Parameters and qualifiers are generally space-delimited - if you wish to include spaces, the parameter or qualifier should be enclosed in quotation marks. Multiple commands on a line are separated with the ";" character. Commands may be continued across lines by using a trailing "-". Characters with special meaning may be escaped with the "\" character to prevent their interpretation. Special characters include: / introduces qualifier space separates command components " encloses components to prevent splitting ; separates commands on a line % introduces script variable \ the escape character itself Remember to use extra escape characters in lines which may be expanded more than once. For example, the line: alarm/icon=test "message \\%$file \\%$type" needs two escape characters to quote the variables, as they are expanded once upon setting the alarm, then again on alarm execution. Unfortunately, the number of escape characters needed in any relatively complex situation like this may not make sense. Where this proves to be a problem, the command may be preceded by the "literal" command to prevent any interpretation of special characters (such as % or \) in that command. This is particularly useful in setting variables for modem initialisation strings. The values of script variables may be substituted into lines by prefixing them with a "%". For example, after the command "set test hello", the command "message %test" expands into "message hello". The output of another command can also be substituted into a line. To do this, the command is enclosed in curly brackets {,}. The return value of the enclosed command will be substituted in its place. For example: set test {?file slipdial:!run} expands to: set test 1 (assuming the file 'slipdial:!Run' has an object type of 1). Another example: message {icon/free} displays the number of free bytes in the slipdial sprite area in a window. Slipdial script commands ------------------------ 1: General ---------- # comment introduces a comment - the line is ignored (and, in fact, not loaded). debug <n> sets debugging level - controls what level of information is sent to the control window and debug file (if any). 0 no debug output 1 script progress 2 text received from modem 3 log both text & script echo [/status] [/date] <string> echoes a string (or set of strings) to the control window (default) or the status window. /date adds the current date to the string before writing. set <variable> <value> [<variable> <value> ... ] assigns a value to a script variable. <value> should be quoted if it includes spaces. More than one variable/value pair may be set at once. unset <variable> deassigns a script variable. ?eq <variable> <variable|value> ?ne <variable> <variable|value> ?lt <variable> <variable|value> ?le <variable> <variable|value> ?gt <variable> <variable|value> ?ge <variable> <variable|value> these test whether a variable is equal, unequal, greater, or less than, another variable or value. Return 1 or 0 for true/false. eval <expression> returns result of mathematical operations (possibly on script variables). eg: set lemming {eval "%lemming + 1"} increments the value of 'lemming' by one. string /size <string> returns size (length) of a string. string /upper <string> converts string to upper case string /lower <string> converts string to lower case string /right=<n> <string> returns rightmost <n> characters of string string /left=<n> <string> returns leftmost <n> characters of string string /start=<n> /length=<n> extracts a substring from a string string/instr=<string2> <string1> returns position of <string2> in <string1> oscli <os command> [<os command> ... ] executes RISC OS commands. Return 1/0 for success/error. osvar <variable> returns value of OS variable oseval <expression> returns results of expression after evaluation by OS_EvaluateExpression. Returned value can be a string or integer. message [/id=<n>] [/add] [/title=<title>] [/capture[=<string>]] [/end=<string>] [/max=<n>] [/wait] <line1> [<line2> ... ] opens a window with a textual message for the user. Each line should be enclosed in quotes. /id=<n> identifies which message window the command applies to. At present there is only one window, and this qualifier is ignored. The ability to specify multiple windows will be added in later versions. /wait qualifier pauses script until user clicks on OK icon or closes message window. /capture[=<string>] will capture serial input to the message window, optionally starting from <string>. (See Notes at end) /end=<string> causes message capture to end when <string> is found. /max=<n> defines a maximum number of lines to capture. /add causes text to be added to an existing message. If no text is given, the command simply forces an update (redraw) of the message window. message [/id=<id>] /close explicitly closes any message window. ask [/delay=<n>] [/default=<yes|no>] <question> brings up a window asking for a yes/no answer from the user. Returns 1 if 'yes' is clicked; 0 if 'no' is clicked. /delay=<n> sets timeout (in seconds). If no response is received within this time, the default answer is returned. /default=<y|n> sets the default answer returned if the command times out. If unspecified, 'no' (0) is assumed. Note that, at present, the default answer is not highlighted in any way on the dialogue window. ?task <taskname> returns task handle of task, or zero if it is not running. error <message> stops the script with an error message (and invokes error handler, if any is installed. help [<command>] gives online help about script commands. "help" by itself gives a list of available help topics. newsrate <abbr> computes the transfer rate of news from the time difference between the xxxNews and xxxNG files, eg: newsrate Dem Returns a value in characters per second. literal prevents variable substitution in the next following command. Useful for such things as setting variable strings containing special characters such as % or \. 2: Script Flow -------------- :<label> marks a label in the script; a destination for 'goto' or 'call'. Spaces should not be used in a label definition. goto <label> transfers execution to the line following the given label. call [/lock] <label> [<parameters>] calls a subroutine, with optional parameters. The parameters are placed into the script variables p1,p2,...,pn within the subroutine. The /lock flag sets a 'lock flag' on the subroutine, which prevents it from being re-entered until it has returned. return [<value>] return from subroutine, optionally passing back a return value. The returned value may be numeric or textual. if (<command>) <command> conditionally executes a command depending on the status returned from another command. For example: if (?file $.lemming) exit exits the script if the file $.lemming exists. You can also negate the test: if (!?file $.lemming) exit case <value|variable> starts a case...when...endcase structure. when <value> [<value> ... ] ; <commands> executes the remainder of the line if one of values matches the current "case" value. Note this only acts on the rest of the same line containing the "when" statement. endcase marks the end of a case...when...endcase structure. library <filename> [<parameters> ... ] appends a script file to the current script for use as a library. If the new file contains a subroutine "autoexec", it will be executed after loading, being passed the parameters given in the library command. source <filename> directly executes script commands from the given file. chain <filename> loads and runs a new script. All variable (except for 'system' variables, beginning with "$"), alarms, menus, etc are cleared. The name of the original script is placed in the system variable "$caller". exit stops the script. quit stops the script and quit the program. stop simulates pressing the 'stop' button. 3: Serial i/o ------------- driver [<name>] loads a modem driver, or sets the default (internal) driver if unspecified. Modem drivers define the strings used to control the modem, and the status messages returned from them. port <driver> <port number> loads the specified block driver, and use specified port number. For example: port sp_dual 1 If not specified, "port internal 0" is assumed. speed <baud> sets baud rate to <baud>. Default is 19200. claim [<attempts> [<delay>]] claims the currently selected port and initialise it, with optional retries if the port is unavailable. Returns 1/0 for success/failure release releases port (also dropping line). init [<string>] drops and raises DTR on serial port to put modem in command mode, and sends the specified string to the modem; then waits for "OK". Returns 1/0 for success/failure. If no string is given, the init strings from the modem driver are sent. reinit resets serial port. retry [<attempts> [<delay>]] sets default number of dialling retries and intervening delay, in seconds. dial [/pulse] [/retry=<n>] [/delay=<n>] [/nodial=<n>] [/nocar=<n>] [/busy=<n>] <number> [<number> ... ] dials the specified number or list of numbers. If a list is given, a number will be tried multiple times (specified by 'retry') before moving on to the next in the list. Returns 1/0 for success/failure. /pulse uses pulse dialling instead of tone. /delay=<n> and /retry=<n> override the default number of retries and delay. /nodial=<n>, /nocar=<n> and /busy=<n> override default redial delays for individual cases (ie, no dialtone, no carrier, busy). Useful, eg, to specify a longer delay for no dialtone (someone using phone). send [/raw] [/noraw] [name=<id>] <string> [<string> ... ] sends a string to the serial port or a taskwindow. /raw prevents a newline. /noraw renables newlines. /name=<id> sends the string to taskwindow <id> rather than the serial port. ?line <condition> tests condition of serial port lines. Condition can be one of: /cts /dsr /rng /dcd Returns 1/0 for high/low 4: Control ---------- wait [/delay=<n>] [/id=<id>] <string1> [<string2>...] waits for a string to be received. You can specify up to 4 strings to wait for. For example: wait login password returns 1 if "login" is detected, 2 if "password" is detected, or 0 if the command times out. The default timeout is 600 seconds (10 minutes); you can alter this with the /delay=<n> qualifier. For example: wait /delay=20 login waits for 20 seconds for the string "login". To include spaces in a wait string, quote the string - eg: wait /delay=20 login "contrived example" HELLO The default input stream examined is the serial (or other) port, as defined by the "port" command. If the qualifier "/id=<id>" is specified, the output stream from the specified taskwindow is examined instead. Note that you can at present only specify a taskwindow which is being buffered to a window; not one with output to a file. wait /event waits for an event such as an alarm or a user menu selection. event [/enable|/disable] <event-type> [<event-type> ... ] enables or disables events. You might want to disable events during sensitive script operations, such as logging in. Events will still be queued while disabled, but will not be acted upon until an "event/enable" is issued. Note that "stop" and "error" events cannot be disabled! Event types are as follows: sys slipdial system events (cannot be disabled) time timed alarms line line alarms task task termination events twin taskwindow termination events input user command input (command window) icon click on user icons file file dropped on user icons menu user-defined menus eof user-file EOF events Event specifications may be combined in one command, eg: event /disable all /enable line menu task alarm /time=<time> [/repeat] [/id=<id>] <action> sets an alarm either for time-of-day or elapsed time. <time> is specified as: HH:MM:SS time of day +HH:MM:SS elapsed time The /repeat qualifier will resubmit the same alarm setting after it goes off. The /id qualifier associates a name with an alarm, so it can be cancelled. alarm /cancel=<id> Cancels a timed alarm. (to cancel a non-timed alarm such as /stop or /dcd, set the alarm with a null command - eg, 'alarm/stop'). alarm /stop=<command> Specifies a command to be executed when the "Stop" button is clicked. If no stop alarm is defined, the serial device is released and the script pauses. This alarm cancels itself when it goes off. alarm /dcd[=0|1] <command> alarm /cts[=0|1] <command> alarm /dtr[=0|1] <command> alarm /rng[=0|1] <command> alarm /dsr[=0|1] <command> Specifies command to execute when the specified line becomes low (or high). This alarm cancels itself when it goes off. Use the '=1' value specification to trigger on low->high, otherwise, triggers on high->low. alarm/error=<command> defines command to execute when a script error occurs. alarm/icon=<id> <command> defines command to execute when a file is dropped onto icon with identifier <id>. The name of the file dropped is put into the variable $file, and its filetype (in hex) into $type. menu "entry:command" ["entry:command"]... defines a user menu (only acted upon during a "wait /event") For example: menu "Call Demon:call calldemon" "Send Mail:call sendmail" "Quit:quit" menu/icon=<id> "entry:command" ["entry:command"]... defines a menu associated with an iconbar icon (added by the 'icon' command). icon/id=<id> [/file=<filename>] [/action=<command>] <spritename> adds an icon to the icon bar. Up to 5 extra icons can be added, each with their own associated actions and menus. /id=<id> identifies the icon (either a new icon or replacement) /file=<filename> loads the named sprite file into slipdial's sprite pool (note, limited space available!) /action=<command> defines script command to execute when icon is clicked. icon/cancel=<id> deletes an icon from the iconbar. icon /free returns the amount of free space in the slipdial sprite area. This can be used to check whether it is possible to load a sprite file. pause <n> sleep <n> Waits for <n> seconds before continuing script execution. If <n> is zero or omitted, puts script into pause mode (restart by clicking on Resume). task [/name=<name>] [/exit=<command>] [/wait] <filespec> starts the specified task. Example: task <TCPIP$Dir>.!Run /name specifies a name to be associated with the command (by which it may be killed, for example). /exit specifies a command to be executed when the task terminates. /wait forces the script to wait for the started task to finish. Otherwise, script execution continues as soon as the task starts (the "/exit" command, if any, being added to the event queue when the task finishes). It is possible to combine the "/wait" and "/exit" qualifiers, but also pointless! task /kill[=<taskname>] task /kill by itself kills the last task to be started by the "task" command. task /kill <taskname> kills a task by name (name as known by the task manager). Only tasks known to SLIPdial (started by the "task" command) can be killed. taskwindow [/name=<name>] [/size=<nK>] [/exit=<command>] [/wait] [/keep] [/output=<filename>] "<external command>" Starts a taskwindow process. /name name for task manager (default is "SDtaskn", where n is a number). /size sets wimpslot size for task (default is size of "Next" slot). /exit defines command to execute when task terminates /output sets file to store output in (if no file specified, all output goes to a buffer window). /nooutput prevents an output window from being opened, though the data is still buffered internally as if a window were present. /wait forces the script to wait for the started task to finish. Otherwise, script execution continues as soon as the task starts (the "/exit" command, if any, being added to the event queue when the task finishes). /keep causes the buffer window, if any, to be kept onscreen after the task finishes. Otherwise, the window is deleted as the task exits. The slipdial taskwindow "slot" cannot be re-used until the window is closed. It is possible to combine the "/wait" and "/exit" qualifiers, but also pointless! taskwindow /kill=<id> kills the given taskwindow. taskwindow /suspend=<id> taskwindow /resume=<id> these commands suspend or resume a taskwindow. dataopen <taskname> <filespec> sends a dataopen message for the specified file to the specified task. ipget [/delay=<n>] <string> waits for <string>, which should mark the start of a dynamically-assigned IP number. The rest of the number will then be captured. Example: ipget 134. The string: Your IP address is 134.84.101.42. is received. The IP number 134.84.101.42 is captured, into the script variable "ipaddress", for use by the "make" or other commands. The variables ip1, ip2, ip3 amd ip4 are also set, to the four components of the IP address. The /delay qualifier sets the command timeout in seconds. If not specified, a timeout of 60 seconds is assumed. make <source> <dest> Makes one file from another, performing variable substitutions. For example, to create an Autoexec file for !TCPIP. Occurances of "%variable" in the source file are replaced by the variable value in the output file. Eg: ip address [%ipaddress] attach asy %port slip ax0 4096 576 %speed route add default ax0 [%ip1.%ip2.%ip3.254] 1 becomes: ip address [134.84.101.42] attach asy sp_dual 1 slip ax0 4096 576 57600 route add default ax0 [134.84.101.254] 1 Specifying output file contents within scripts: You can take lines from the script as well as from an input file. Script lines following the "make" command which have a "+" as the first character will be used as source lines for the output file (the + character being stripped off). Specify an input file of "-" to use only these script lines. If you specify both a real input file and + lines, the + lines will be used after the input file has been processed. Comment lines (those beginning with a "#") in the source file are not transferred to the output file. list /var list /tasks list /menus list /script [<first> [<last>]] list /alarms list /files Lists current variables, tasks, menus, script, alarms, or open userfiles to the debug window. ?free [/mem] [/next] [/free] [/device=<filespec>] [/int] returns amount of free memory: /mem returns all free memory, ie next+free slots /next returns size of 'next' slot /free returns size of 'free' slot /device returns amount of space left on the device holding <filespec> /internal returns internal free space within slipdial application input [/prompt=<prompt>] [/hide] <variable> [[/prompt=<prompt2>] <variable2> ... ]] Prompts the user for input in a window, and place the input in a script variable. Multiple prompts/inputs can be combined in one command. The /hide qualifier prevents the typed response from being displayed (for example, when entering passwords). 5: File commands ---------------- move <file1> <file2> moves a file from one location to another. (a rename is tried first; if that fails, a copy with source delete is tried). copy [/head=<n> /tail=<n>] <file1> <file2> copies one file to another. With either the /head or /tail qualifier, copies only the first or last <n> lines of the file. If <n> is unspecified, a default of 50 is used. For both move and copy, a '*' within the destination filename is replaced with a 4-digit random number such that the destination file is guaranteed unique. The created destination filename is also stored in the script variable '$dest', for later reference. append <file1> <file1> appends file1 to file2 (if file2 doesn't exist, it is created). delete <file> deletes a file. ?file <filename> ?file itself returns object type of file 0 doesn't exist 1 file 2 directory 3 image file Other qualifiers available: /size returns the size (in bytes) of the given object. /type returns the (hex) filetype. /attrib returns the file attributes (bit 0 = read access, etc). /expand returns the canonicalised filename. /leaf returns the leafname of <filename>. /path returns the path component of <filename>. trace <filename> opens <filename> as a debugging logfile. All output which appears in the debug window is also sent here. (currently excepting taskwindow output). open /id=<id> [/error=<command>] [/read|/write|/rw] <filename> Opens the named file for read, write or read-write access, associating the given identifier with the file. The /error qualifier defines a command to execute if the file open fails. close /id=<id> Closes the file with the given identifier. read /id=<id> [/eof=<command>] <variable> [<variable> ... ] Reads lines from the given file into script variables. The /eof qualifier defines a command to execute if end-of-file is reached during the read oeration. write /id=<id> <data> [<data> ... ] Writes textual data into the given file. ptr /id=<id> [/set=<n>] [<variable>] Reads or sets the pointer into the named file. Without the "/set" qualifier, returns the file pointer (optionally setting the named variable). With the /set qualifier, sets the file pointer. "/set=eof" sets the pointer to end-of-file. 6: Script Variables ------------------- Variable substitution takes place on each line in the script during execution. A variable is specified by the prefix "%"; for example: set lemming goto start %lemming would execute the command "goto start". Some variables are defined automatically during script execution. These are: $status contains values returned from script commands, often indicating success or failure, but can indicate more detailed results. port contains driver and port in use (set by "port" command) speed contains baud rate (set by "speed" command) ipaddress contains IP address detected by "ipget" command. Setting this variable causes automatic recalculation of the variables ip1,ip2,ip3,ip4, and updates the "IP" address field in the status window. ip1,ip2,ip3,ip4 contain the four components of a detected IP address. route set to %ip1.%ip2.%ip3.254 by "ipget", but you can of course alter it yourself. p1 p2 p3 (etc) parameters passed to a subroutine. Note these are NOT preserved throughout the execution of the subroutine and will be destroyed by further calls to other routines. Transfer values to variables of your own if you want to keep them for later use. 7: Notes -------- Alarm scheduling is done using OS_ReadMonotonicTime. Things may (certainly will!) break when the timer wraps around to a negative value. Will possibly be fixed someday, but not terribly likely! Some functions operate in slightly unexpected ways. The correct way to use the "message/capture" command is not obvious, for example. It does not, in fact, examine the serial input stream itself at all; but merely installs a "filter". For text to be captured, you then need to use a command which does examine the input stream - examples being "wait", "ipget", etc. To avoid flicker, the message window is not updated on every captured line. Instead, it gets refreshed whenever a blank line is received. A four-second timer also causes a refresh if the contents change but the window is not updated for that long. An update can be forced by adding a blank line to the window: "message/add". Blank lines are not added to the display list; they simply cause a refresh. "task/exit" and "taskwindow/exit" also need some explanation. These commands enable another script command to be executed when the started task finishes. How this operates is to add the "exit command" to the event queue when task termination is detected. After the "task/exit" command, script execution continues immediately after the task starts; the exit command, therefore, can be triggered at any future point in the script. For most simple commands, or even most subroutine calls, this presents no problem, but obviously "goto" commands and suchlike should probably be avoided. For particulary critical routines, where the execution of a lengthy event-command could disrupt things - for example, during a login sequence - event processing can be disabled, using the "event/disable[=<type>]" command. The script can stay in the dialling routine for a relatively long time. During this time, events (alarms, menus, etc) are not acted upon. The pause, stop, and redial buttons are active in the status window. Currently hard-coded limits are: Script line limit 2000 (but memory management may not cope with a script this size, at present!) Items per user menu 30 (255 character limit total for each of description & command lists) Timed alarms 10 Simultaneous tasks 8 ('task' command) Simultaneous taskwindows 8 ('taskwindow' clients) Variables 150 Goto/call destinations 50 Subroutine levels 20 Case...when...endcase levels 10 Simultaneous 'wait' strings 4 Pending events 10 Open "user" files 10 User icons 8 ---------------------------------------------------------------------------- Disclaimer! ----------- SLIPdial is probably still full of bugs. Most things seem to work okay, but the increasing complexity of the script language, plus the fact that the program was simply cobbled together over time, makes exhaustive checking difficult. However, I would like to thank several people for testing slipdial during the rapidly-changing versions between 0.23 and 0.30:- Robert Orwin rob@wong.demon.co.uk Ian Stocks ian@frogstar.demon.co.uk Andrew Black andrew@bach.demon.co.uk Paul Allen pla@sktb.demon.co.uk Rick Hewitt rick@chocky.demon.co.uk also many others who pointed out bugs or made suggestions. Any problems, suggestions or questions can be sent to me via email at: allan@mnhep1.hep.umn.edu 
